클로드 완벽가이드 (입문) — 1장 왜 클로드 코드인가

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 4가지만: 첫째, 예전 AI 코딩이 왜 답답했는지 그 네 가지 이유를 안다. 둘째, 에이전틱 AI가 그걸 어떻게 풀었는지 설명한다. 셋째, 클로드 코드의 4단계 일하는 방식을 따라 읽는다. 넷째, 클로드 코드가 다른 도구와 무엇이 다른지 구분한다.

이 장은 "왜 하필 이 도구냐"에 답하는 장이다. 기능 사용법은 아직 안 나온다. 그건 다음 장들 몫이다. 여기서는 이 책 전체를 관통하는 큰 이유 하나를 잡고 간다.

학습 목표 이 장을 마치면 이렇게 할 수 있다. 예전 AI 코딩의 네 가지 한계를 설명한다. 에이전틱 AI가 그 한계를 어떻게 푸는지 구분한다. 클로드 코드의 4단계 작동 흐름을 따라 한다(읽으며 그려본다). 클로드 코드와 다른 코딩 도구의 차이를 설명한다.

참고로 이 장은 0장 용어집을 옆에 두면 훨씬 쉽다. 에이전틱 AI, 클로드 코드, 콘텍스트, 플래닝 모드, 토큰, 모델 같은 말이 나오면 0장에서 이미 풀어놨다. 모르면 거기로 돌아가면 된다.

0. 미리 챙길 준비물 (선수 지식)

본격적으로 들어가기 전에, 이 장을 편하게 읽으려면 아래 네 가지를 한 번쯤 해본 적이 있으면 좋다. 없어도 괜찮다. 모르면 0장 용어집에서 찾으면 된다.

체크리스트. 변수, 함수, 파일 같은 아주 기본적인 프로그래밍 말을 들어봤다. 검은 화면(터미널)에 글자를 쳐서 명령해본 적이 있다. ChatGPT 같은 AI 챗봇에 질문해본 적이 있다. VS Code나 커서 같은 코드 편집기를 켜본 적이 있다.

1. 먼저, 이렇게 막힌 적 있죠?

상상해 보자. 바쁜 와중에 ChatGPT에게 "로그인 기능 만들어줘"라고 했다. 코드가 나왔다. 그런데 내 프로젝트에 붙여넣으니 안 맞는다. 내가 React를 쓰는지 Vue를 쓰는지 AI는 몰랐던 거다. 이미 깔아둔 라이브러리를 또 깔라고 한다. 에러가 나서 에러 메시지를 복사해 다시 물어본다. 또 안 맞는 코드가 온다. 이 왕복을 열 번쯤 하다 보면 차라리 내가 짜는 게 빨랐겠다 싶다.

이 답답함의 정체가 이 장의 출발점이다. 예전 AI는 "단어는 잘 번역하는데 대화 맥락은 모르는 통역사" 같았다. 그게 무엇이고 왜 그랬는지, 그리고 어떻게 풀렸는지를 지금부터 본다.

콘텍스트(Context)란, 프로젝트 전체의 맥락과 구조 정보를 말한다. 책상 위에 펼쳐둔 자료 전체에 비유한다(0장 2-9 참고).

2. 예전 AI 협업의 네 가지 한계

2-1. 한 줄로 먼저

예전 AI 코딩 도구(초창기 ChatGPT, 코드 자동완성류)는 똑똑했지만 "자동 완성" 수준에 머물렀다. 거기엔 네 가지 공통된 답답함이 있었다.

배경 숫자 하나만 짚자. 원서/노트 기준 예시로, 2025년에 많은 기업이 AI 도입을 추진했지만, 상당수가 "개발 과정에 녹여 넣는 일"을 가장 어려운 숙제로 꼽았다. 즉 문제는 기술 자체보다 "어떻게 실무에 붙이느냐"였다. (이런 구체 수치는 시간이 지나면 바뀐다. 흐름만 기억하면 된다.)

2-2. 한계 1 — 맥락의 부재

가장 큰 문제다. AI가 내 프로젝트 사정을 모른 채 일반론적인 코드만 뱉는다.

비유. 새 동네 식당에 처음 온 손님 같다. "늘 먹던 걸로요"라고 해도 점원이 내 단골 취향을 모르니 엉뚱한 걸 내온다.

잘못된 예 vs 올바른 예.

[잘못된 흐름 — 맥락 없는 AI]
나: "로그인 기능 만들어줘"
AI: (React인지 Vue인지 모른 채) 일반 HTML 폼을 만듦
    내 코딩 스타일 무시
    이미 깔린 라이브러리를 또 깔라고 함

[올바른 흐름 — 맥락 있는 AI]
나: "로그인 기능 만들어줘"
AI: "이 프로젝트는 React + Express군요. 기존 JWT 방식에 맞춰 짜겠습니다"

이럴 때 이렇게. 맥락 없는 AI를 쓸 땐 내가 매번 "React야, 인증은 JWT야, 스타일은 이렇게 해"를 다 말해줘야 한다. 그게 빠지면 결과가 어긋난다.

2-3. 한계 2 — 파편화된 워크플로

작업이 세 군데로 쪼개진다. 코드 편집기, AI 채팅창, 터미널을 계속 오간다. 복사하고 붙여넣기를 반복하다 생각의 흐름이 뚝뚝 끊긴다.

비유. 재료는 냉장고, 레시피는 휴대폰, 불은 옆방에 있는 부엌 같다. 한 번 요리하는데 세 방을 왕복하니 음식이 식는다.

[파편화된 흐름]
편집기 ←(복사)→ AI 채팅창 ←(붙여넣기)→ 터미널
       이 왕복이 반복되며 집중이 깨짐

이럴 때 이렇게. 한곳에서 다 되면 좋겠다는 생각이 든다면, 그게 바로 이 한계를 겪고 있다는 신호다.

2-4. 한계 3 — 마이크로매니지먼트가 필요함

마이크로매니지먼트란, 세세한 것까지 하나하나 일일이 지시하는 관리 방식을 말한다. 신입에게 "파일 열어, 3번째 줄에 이거 써, 저장해, 테스트 돌려"를 전부 불러주는 것과 같다.

비유. 젓가락질부터 가르쳐야 하는 막내. 하나 시키면 하나 한다.

[하나하나 지시해야 하는 AI]
나: "파일 만들어"   → AI: (만듦)
나: "이 함수 추가해" → AI: (추가함)
나: "테스트 작성해"  → AI: (작성함)
나: "이 부분 고쳐"    → AI: (고침)
→ 지시가 코드 짜기만큼 번거로움

이럴 때 이렇게. "이걸 일일이 말할 바엔 내가 짜겠다"는 생각이 들면, 그게 마이크로매니지먼트의 피로다.

2-5. 한계 4 — 수동적 실행

수동적이라는 건, 먼저 나서지 않고 시킬 때까지 기다린다는 뜻이다. 버그를 봐도 내가 묻기 전엔 입을 꾹 다문다.

비유. 회의에서 답을 알면서도 호명해야만 말하는 동료. 먼저 손은 안 든다.

[수동적인 AI]
버그 발견 → 개발자가 물어볼 때까지 침묵
아키텍처 개선 제안 → 안 함
보안 취약점 발견 → 모른 척

잘못된 예 vs 올바른 예.

[수동적] 나: "왜 느려?" → AI: (그제서야) "쿼리가 비효율적이네요"
[능동적] AI: (묻기도 전에) "이 쿼리에 N+1 문제가 보입니다. 조인으로 바꿀까요?"

2-6. 한 걸음 더 ▸ 속도는 빨라졌는데 왜 부족했나

예전 도구도 분명 도움은 됐다. 원서/노트 기준 예시로, 어떤 코드 자동완성 도구는 개발 속도를 절반 넘게 끌어올렸다는 조사도 있었다. 그런데 빨라진 만큼 품질이 보장되진 않았다. 빨리 쓴 코드에 맥락이 빠져 있으면, 결국 고치는 시간이 더 들기도 했다. 그래서 진짜 문제는 "속도"가 아니라 "맥락과 자율성"이었다. (여기 등장한 수치는 예시다. 최신 값은 클로드 코드 공식 문서나 원자료에서 확인하면 된다.)

3. 그래서 등장한 것 — 에이전틱 AI

3-1. 한 줄로 먼저

에이전틱 AI는 시키는 한 단계만 하는 게 아니라, 스스로 계획하고 실행하고 검증하는 AI다. "보조"에서 "동료"로 한 단계 올라선 셈이다.

에이전틱 AI(Agentic AI)란, 스스로 계획을 세우고 실행하는 자율형 AI를 말한다. "이 일 해줘" 하면 알아서 처리하는 경력 동료에 비유한다(0장 2-10 참고).

3-2. 보조에서 동료로 (pair → peer)

예전 AI는 페어 프로그래머(보조)에 가까웠다. 페어 프로그래머란, 옆에서 거드는 짝 역할의 AI를 말한다. 지시를 기다리는 수동적 보조다.

새 AI는 피어 프로그래머(동료)다. 피어 프로그래머란, 동료 수준으로 알아서 일하는 AI를 말한다.

비유. 예전이 "시키는 대로만 하는 신입"이었다면, 지금은 "알아서 일하는 경력 동료"다. 신입에겐 "파일 열고, 3줄에 쓰고, 저장하고, 테스트해"라고 다 불러줘야 한다. 경력 동료에겐 "로그인 기능 만들어줘" 한마디면 된다.

3-3. 에이전틱 AI가 실제로 하는 다섯 가지

이 AI는 막연한 한 마디를 받아 일을 끝까지 끌고 간다. 다섯 가지 예를 보자.

1. 새 기능 구현
   "결제 시스템 추가해줘"
   → 파일 만들고, 코드 쓰고, 기존 코드 수정까지

2. 라이브러리 검색·설치
   "이메일 발송 기능 필요해"
   → 알맞은 도구 설치, 설정 파일 생성, 예제 코드까지

3. 테스트 작성·실행
   "이 API 테스트 만들어줘"
   → 테스트 작성 → 실행 → 실패하면 자동 수정

4. 버그 재현·수정 제안
   "로그인이 안 돼"
   → 로그 분석 → 원인 파악 → 고칠 코드 제안

5. 개발 도구 자동 설치·적용
   "코드 검사 도구 설정해줘"
   → 설치 → 설정 파일 생성 → 기존 코드에 적용

이걸 가능하게 하는 게 에이전틱 워크플로다. 에이전틱 워크플로란, AI가 복잡한 여러 단계 작업을 알아서 순서대로 처리하는 흐름을 말한다. 요리로 치면 "재료 준비 → 손질 → 조리 → 간 보기"를 한 번에 맡기는 것과 같다.

여기서 잠깐, 이 일하는 방식에 붙은 이름이 하나 있다. "결제 시스템 추가해줘"처럼 코드 한 줄 안 쓰고 말로만 기획을 던져서 만드는 방식 말이다.

용어 한 줄: 이렇게 자연어로 AI에게 기획과 지시를 줘서 코딩하는 방식을 바이브 코딩(Vibe Coding)이라고 불러요. (말로 분위기만 잡아주면 AI가 알아서 짜는 것 — 마치 노래방에서 "신나는 거"라고만 해도 알아서 곡을 골라주는 것처럼요.)

4. 일하는 방식이 바뀌면, 사람의 역할도 바뀐다

4-1. 한 줄로 먼저

AI가 코드를 대신 짜기 시작하면서, "잘하는 개발자"의 기준이 바뀐다. 예전엔 코드를 많이 빨리 짜는 사람이었다. 이제는 무엇을 왜 만들지 정하고, 결과를 날카롭게 검토하는 사람이다.

비유. 예전엔 벽돌을 많이 쌓는 사람이 유능한 건축가였다. 이제는 어떤 건물을 지을지 설계하고, 안전한지 감리하는 사람이 유능한 건축가다. 벽돌 쌓기(코딩)는 AI가 한다.

4-2. 생산성의 새 기준

예전 기준은 "코드를 얼마나 많이 썼는가"였다. 새 기준은 "얼마나 가치 있는 문제를 풀었는가"다.

잘못된 예 vs 올바른 예.

[옛 기준] "오늘 500줄 짰어"  → 양으로 평가
[새 기준] "결제 실패율을 절반으로 줄였어" → 해결한 가치로 평가

4-3. 개발자의 세 가지 새 역할

역할 1: 방향 제시
──────────────
"우리 서비스는 모바일 우선이야.
 응답은 200밀리초 안으로.
 데이터베이스는 PostgreSQL, API는 REST로 설계해줘."
→ 목표와 제약을 분명히 정해 준다

역할 2: 비판적 검토
──────────────
AI가 짠 코드를 보고:
"이 쿼리는 N+1 문제가 있어. 조인으로 바꿔."
"이 API에 인증 미들웨어가 빠졌어."
"에러 처리가 너무 허술해."
→ 품질·보안·구조를 날카롭게 본다

역할 3: 최종 문제 해결
──────────────
AI가 잘 못 푸는 영역:
- 어떤 기능을 먼저 만들지 우선순위 결정
- 오래된 시스템과 합치는 전략
- 사용자가 편하게 느낄 화면 설계
→ 창의적 판단이 필요한 큰 문제에 집중한다

이럴 때 이렇게. AI가 코드를 척척 내놓는다고 그대로 믿지 말자. "방향을 내가 정했나, 결과를 내가 검토했나"를 항상 챙기면 된다. 참고로 잘 만든 에이전틱 AI는 웬만한 주니어 개발자 수준의 결과를 내놓기도 한다. 그래서 사람에게는 더 높은 차원의 판단력이 중요해진다.

5. 그래서, 클로드 코드란 무엇인가

5-1. 한 줄로 먼저

클로드 코드는 앤트로픽이 만든, 터미널 안에서 일하는 에이전틱 AI 개발 동료다. 받은 요청을 분석 → 계획 → 실행 → 검증의 4단계로 알아서 처리한다.

비유. "오늘 우리 팀에 합류한 시니어 개발자"다. 첫날 코드베이스를 쭉 읽고(분석), 어떻게 할지 정하고(계획), 직접 짜고(실행), 테스트 돌려보고 문제가 있으면 스스로 고친다(검증). 다른 점은 단 하나, 이 시니어가 내 터미널 안에 산다는 것뿐이다.

(클로드 코드는 앤트로픽의 똑똑한 AI 모델을 두뇌로 쓴다. 모델 이름과 종류는 시간이 지나면 바뀌므로, 정확한 최신 모델명은 클로드 코드 공식 문서에서 확인하면 된다.)

5-2. 4단계 워크플로 — 따라 읽어 보기

아래는 "사용자 인증 시스템을 만들어줘"라고 한 마디 했을 때, 클로드 코드가 속으로 밟는 네 단계다.

먼저 터미널에서 클로드 코드를 켠다.

$ claude
> 사용자 인증 시스템을 구현해줘

그러면 이렇게 진행된다.

[1단계: 프로젝트 구조 분석]
- 코드베이스 탐색  → "src/ 아래 컴포넌트가 있군요"
- 프레임워크 파악  → "Next.js와 Prisma를 쓰네요"
- 코딩 패턴 학습   → "함수형 컴포넌트 스타일이군요"

[2단계: 작업 계획 수립]
- 필요한 부품 식별 → 로그인 폼, 회원가입 폼, 인증 처리부
- 구현 순서 결정   → DB 구조 → API → 화면
- 종속성 파악     → 비밀번호 암호화·토큰 도구 필요

[3단계: 실행]
- 파일 생성·수정
- 코드 작성
- 필요한 패키지 설치
- 테스트 코드 작성·실행

[4단계: 검증 및 개선]
- 작성한 코드 테스트 → 통과 확인
- 오류 발견 시 자동 수정 → 타입 에러 1건 고침
- 코딩 스타일 통일 → 기존 컨벤션에 맞춤

이 4단계를 한 문장으로 외우자. "읽고(분석) → 정하고(계획) → 짓고(실행) → 점검한다(검증)."

5-3. 클로드 코드가 맥락을 이해하는 세 가지 방식

2절에서 예전 AI의 가장 큰 한계가 "맥락 부재"였다. 클로드 코드는 바로 그 지점을 이렇게 푼다.

1. 깊은 코드베이스 이해
   지금 연 파일만이 아니라, 프로젝트 전체 구조와
   파일끼리의 관계까지 파악한다.

2. 암묵적 규칙 학습
   "이렇게 짜라"고 안 적어둔 숨은 코딩 관습·패턴도
   알아서 눈치챈다.

3. 의존성 관계 추적
   한 코드를 바꾸면 다른 어디에 영향이 갈지를
   미리 따져본다.

비유. 새 팀에 온 베테랑이 첫 주에 회사 분위기, 암묵적 규칙, 부서 간 관계를 빠르게 읽어내는 것과 같다.

5-4. 한 걸음 더 ▸ "비판적 검토"를 연습해 보기

4-3에서 배운 "비판적 검토" 역할을 짧게 연습하자. 아래는 AI가 짰다고 가정한 API 코드다.

app.get('/users', (req, res) => {
  const users = db.query('SELECT * FROM users');
  res.json(users);
});

여기서 사람이 잡아야 할 문제 셋(+덤 하나).

1. 인증·인가 장치가 없음
   → 아무나 전체 사용자 목록을 볼 수 있다(보안 문제)
2. SELECT * 로 다 가져옴
   → 비밀번호 같은 민감 정보까지 노출될 수 있다
3. 에러 처리가 없음
   → DB 연결이 끊기면 서버가 그대로 멈출 수 있다
(덤) 페이지 나눔(페이지네이션)이 없음
   → 사용자가 수만 명이면 한 번에 다 불러와 느려진다

핵심. AI가 코드를 줬다고 끝이 아니다. 이렇게 보안·민감정보·에러·성능을 짚는 게 사람의 몫이다.

6. 클로드 코드는 다른 코딩 도구와 무엇이 다른가

6-1. 한 줄로 먼저

클로드 코드와 다른 코딩 도구(예: 커서 같은 통합 개발 환경)는 같은 AI 모델을 쓸 수도 있다. 그런데도 성능, 비용, 실행 환경, 계획 기능에서 차이가 난다. 핵심 이유는 클로드 코드가 에이전틱 워크플로에 맞춰 다듬어졌기 때문이다.

비유. 같은 엔진을 단 차 두 대를 떠올리자. 한쪽은 화면 예쁜 고급 세단(통합 개발 환경) — 편하지만 정해진 길 위주다. 클로드 코드는 오프로드 지프(터미널 기반) — 화면은 단순해도 4륜구동(에이전틱 워크플로)으로 험한 길도 간다.

6-2. 한눈에 보는 비교표

┌──────────────┬───────────────────────┬───────────────────────┐
│    항목       │     클로드 코드         │   다른 통합 개발 도구    │
├──────────────┼───────────────────────┼───────────────────────┤
│ 성능          │ 에이전틱 워크플로 최적화 │ 모델 입출력 위주         │
│              │ → 복잡한 일에 강함      │ (같은 모델이라도 차이)   │
├──────────────┼───────────────────────┼───────────────────────┤
│ 비용          │ 구독제로 정액 사용 가능 │ 구독 + 별도 사용료 구조   │
│              │ (예시값, 공식에서 확인) │ 고성능 모델 쓰면 비싸짐   │
├──────────────┼───────────────────────┼───────────────────────┤
│ 실행 환경     │ 터미널 기반            │ 전용 편집기 환경          │
│              │ 쓰던 편집기 그대로 유지 │ 그 편집기를 써야 함       │
├──────────────┼───────────────────────┼───────────────────────┤
│ 플래닝(계획)  │ 매우 강력              │ 제한적                  │
│              │ 코드 없이 계획만 가능   │                        │
└──────────────┴───────────────────────┴───────────────────────┘

6-3. 비용은 어떻게 보면 되나

원서/노트 기준 예시로 설명한다(숫자는 예시다). 클로드 코드는 정액 구독제로 일정 비용을 내고, 정해진 주기마다 사용량이 새로 채워지는 식이다. 한 번에 여러 에이전트를 돌리며 꽤 긴 시간 작업해도 정액 안에서 쓸 수 있어, 무겁게 쓰는 사람에게 비용이 예측 가능하다.

반면 사용량마다 따로 과금되는 방식으로 고성능 모델을 많이 쓰면, 비용이 가파르게 오를 수 있다. 그래서 작업량이 많다면 정액 구독이 합리적인 경우가 많다.

여기서 꼭 기억할 점. 요금, 플랜 이름, 사용 주기, 한도 같은 숫자는 시간이 지나면 바뀐다. 이 책의 숫자는 원서/노트 기준 예시이며, 최신 값은 공식 문서(클로드 코드 공식 문서)에서 확인하면 된다.

6-4. 플래닝 모드 — 클로드 코드의 간판 기능

플래닝 모드는 코드를 바로 안 짜고, 계획만 먼저 세우는 모드다(0장 2-13 참고). 요리 전 레시피부터 짜는 것과 같다.

왜 좋은가. 복잡한 작업일수록, 바로 코드부터 쏟아내면 방향이 틀렸을 때 되돌리기 어렵다. 먼저 설계도(계획)를 받아 검토하면 큰 실수를 미리 막는다.

[플래닝 모드 흐름]
나: "바로 만들지 말고, 어떻게 할지 계획부터 보여줘"
클로드 코드: (코드 작성 X)
           "1) DB 구조 설계  2) API 작성  3) 화면 연결 …"
나: (계획 검토 후) "좋아, 진행해"

(모드를 어떻게 켜고 바꾸는지 같은 조작법은 이 장에서 다루지 않는다. 지금은 "계획만 먼저 보는 기능이 있다"만 기억하면 된다.)

6-5. 한 걸음 더 ▸ "이미 다른 도구를 쓰는데, 또 깔아야 하나?"

자주 나오는 질문이다. "전용 편집기를 이미 쓰는데 클로드 코드를 추가로 써야 하나요?"

이 장의 내용으로 답하면 이렇다.

추천: 병행 사용

이유
1) 클로드 코드는 터미널 기반이라 쓰던 편집기와 부딪히지 않고 같이 쓸 수 있다
2) 복잡한 작업(기능 전체 구현, 큰 리팩토링)에서 에이전틱 워크플로가 강하다
3) 플래닝 모드로 코드 짜기 전에 설계를 검토할 수 있다

실전 나눠 쓰기
- 간단한 줄 수정 → 쓰던 편집기
- 새 기능 전체 구현·버그 추적·구조 설계 → 클로드 코드

7. 정리 — 예전 vs 지금 한 장 비교

지금까지의 내용을 한 표로 모은다. 이 표 하나만 머리에 남겨도 이 장은 성공이다.

8. 미니 시나리오로 굳히기 (연습)

시나리오 A — 같은 작업, 두 방식

"회원가입 이메일 인증 기능"을 만든다고 하자.

[예전 AI 방식]
1) "이메일 인증 코드 만들어줘" 입력
2) 코드 복사 → 편집기에 붙여넣기 → 안 맞아서 수정
3) 에러 → 메시지 복사 → 다시 질문 → 반복…

[에이전틱 AI(클로드 코드) 방식]
1) "회원가입에 이메일 인증 붙여줘" 한 번 요청
2) 프로젝트 분석 → 기존 인증 방식 파악 → 계획 수립
3) 코드 작성 → 테스트 실행 → 오류 수정까지 자동

차이의 핵심은 "왕복 횟수"와 "맥락"이다.

시나리오 B — 도입을 고민하는 동료에게

동료가 "이미 다른 도구 쓰는데 굳이?"라고 묻는다면, 6-5의 답을 그대로 쓰면 된다. "병행하세요. 간단한 건 쓰던 도구로, 복잡한 건 클로드 코드로."

9. 이 책이 앞으로 데려갈 곳 (이 장은 여기까지)

이 책은 "왜(1장) → 설정 → 기본 조작 → 고급 워크플로 → 실전 제작 → 생태계 도구 → 자동화" 순으로 한 줄기로 이어진다. 전체 지도는 0장 3절(이 책의 척추)에 한 표로 있다. 지금은 그 큰 흐름만 알면 충분하다.

기억할 한 줄. 앞 절반은 도구를 다루는 법, 뒤 절반은 그 도구로 진짜 결과물을 만드는 법이다.

(참고로 Super Claude, Claudia, Claude Squad, ccusage, Claude Code Action, Claude Code Hooks 같은 확장·자동화 도구 이름이 0장에 나왔다. 그건 이 책 뒤쪽 생태계·자동화 파트에서 다룬다. 지금 몰라도 된다.)

다음 장 예고

다음 장은 클로드 코드를 실제로 쓰기 위한 "요금제 고르기"를 다룬다. 어떤 플랜이 있고, 내 작업량에 어떤 게 맞는지 고르는 기준을 본다. 지금 그 내용을 몰라도 된다. 이 1장에서 "왜 클로드 코드인가"만 잡았으면 충분하다.